Before you proceed, please read Sectioná6.5, “Introduction to Host Interface Networking (HIF)”.
There were some changes to the way dynamic host interface configuration is done in VirtualBox 1.4.0, due to changes in Linux kernel versions 2.6.18 and later. Also, this entire section of the manual was rewritten for Virtual 1.4.0. Please reread these sections if you used dynamic interfaces on earlier versions.
Since the Linux kernel has built-in support for virtual network
devices (so-called TAP interfaces), VirtualBox on Linux makes use of these
instead of providing custom host networking drivers. The TAP interfaces
behave like physical network interfaces on your host and will work with
any networking tools installed on your host system. From the point of view
of the host, it looks like the guest's network card is connected to the
TAP interface with a network cable. In order to use Host Interface
Networking in VirtualBox, you must have access to the device
/dev/net/tun
. Check which group this
device belongs to and make sure that any users who need access to
VirtualBox Host Networking are members of this group. In most cases, this
device will belong to the vboxusers
group.
On Linux hosts, you have a choice of creating permanent networking interfaces which guests can attach to when they are created or having VirtualBox create a dynamic interface for a guest when the guest is started and remove it when the guest is stopped. Permanent interfaces are more suitable for hosts with a known set of guests that does not change often (such as some server setups), and they are easier to set up. Having VirtualBox create the interfaces dynamically provides more flexibility, but will normally require you to enter an administrator password each time an interface is created or removed.
On Linux hosts, setting up a permanent host interface using bridging typically consists of three steps:
First, you must create a bridge on the host and add one of
the host's physical network interfaces to it, usually
eth0
. This will let you connect
that interface to the virtual interfaces used by the virtual
machines.
Keep in mind that bridging is an Ethernet concept, not a TCP/IP one. In physical networking, bridging is normally used to connect two Ethernet networks, letting computers on the one communicate with computers on the other through a single point of contact without having to merge the networks into one.[12]
For each guest network card that uses host interface
networking, you must create a new "virtual" host interface
(usually called vbox0
or similar)
and add this interface to the bridge.
Finally, specify the name of the new host interface in the settings of the virtual machine's virtual network card.
Unfortunately, Linux distributions differ substantially in how networking is configured. As we cannot provide instructions for all Linux distributions, we have restricted ourselves to describing how to set up bridging on Debian, Ubuntu, Fedora/Red Hat and openSUSE; in addition, we offer some generic instructions for advanced users.
VirtualBox ships with two utilities,
VBoxAddIF
and
VBoxDeleteIF
, which work on all
distributions. These tools allow you to create and delete permanent host
interfaces (which will automatically be recreated every time you boot
your host computer) and optionally add them to an existing bridge. We
also provide a utility called
VBoxTunctl
which you can use to create
a temporary interface. These tools are described in Sectioná6.8.1.5, “Host Interface Networking utilities for Linux”. Even if you use plan to use host interfaces to
create other networking setups than what we describe here, we recommend
that you read the following instructions in order to get an
understanding of how the interfaces work.
Some distributions -- such as Debian and Ubuntu -- have built-in tools to create host interfaces; you may also use those tools on those distributions.
To set up a permanent host interface on a modern Debian or Ubuntu host, follow these steps:
First install the bridge utilities
(bridge-utils
). package. You
can do this from the command line as follows:
sudo apt-get install bridge-utils
Next, you must add an entry to the file
/etc/network/interfaces
to
describe the bridge. The following sample entry creates a bridge
called br0
, adds the host
ethernet interface eth0
to it
and tells it to obtain an IP address using DHCP so that the host
remains able to access the network.
auto br0 iface br0 inet dhcp bridge_ports eth0
You will probably want to change this to suit your own networking needs. In particular, you may want to assign a static IP address to the bridge. You will find more documentation in the files
/usr/share/doc/bridge-utilities/README.Debian.gz
and
/usr/share/doc/ifupdown/examples/network-interfaces.gz
.
Restart networking on the host:
sudo /etc/init.d/networking restart
After this the bridge will be recreated every time you boot your host system.
Now, to create a permanent host interface called
vbox0
(all host interfaces
created in this way must be called
vbox
followed by a number) and
add it to the network bridge created above, use the following
command (see Sectioná6.8.1.5, “Host Interface Networking utilities for Linux” for more
details):
sudo VBoxAddIF vbox0 <user> br0
Replace <user>
with
the name of the user who is supposed to be able to use the new
interface.
To tell VirtualBox to use the interface, select the
virtual machine which is to use it in the main window of the
VirtualBox application, configure one of its network adapters to
use Host Interface Networking (using "Settings", "Network",
"Attached to") and enter vbox0
into the "Interface name" field. You can only use a given
interface (vbox0
,
vbox1
and so on) with a single
virtual network adapter.
Alternatively, you can use the VBoxManage command line tool (in this example we are attaching the interface to the first network card of the virtual machine "My VM"):
VBoxManage modifyvm "My VM" -hostifdev1 vbox0
To set up a host interface using Debian and Ubuntu's native methods, do the following instead of step 4 above:
First install the User Mode Linux utilities package
(uml-utilities
), which contains
tools to create TAP interfaces. You can do this from the command
line as follows:
sudo apt-get install uml-utilities
In
order for VirtualBox to be able to access the interface, the
user who will be running the virtual machine must be added to
the group uml-net
, for example
with the following command (replace
<user>
with your user
name):
sudo gpasswd -a <user> uml-net
You will have to log in again for the change to take effect.
To describe the TAP interface to your Debian or Ubuntu
system, add an entry to the file
/etc/network/interfaces
. This
names the the interface and must also specify the user who will
be running the virtual machine using the interface.
The following sample entry creates the interface
tap0
for the user
<user>
(again, replace
with your user name):
auto tap0 iface tap0 inet manual up ifconfig $IFACE 0.0.0.0 up down ifconfig $IFACE down tunctl_user <user>
You will probably want to change the entry based on your
networking needs. The file
/usr/share/doc/uml-utilities/README.Debian
on your host computer will have additional documentation.
To add the TAP interface to the bridge, replace the line
bridge_ports eth0
in the bridge section in
/etc/network/interfaces
with
bridge_ports eth0 tap0
Restart networking on the host:
sudo /etc/init.d/networking restart
At least openSUSE 11 has a udev rule which calls
/sbin/ifup
for each network interface
created with ifconfig
. Calling
ifup
for host network interfaces will
not work as the openSUSE system has no configuration about this
interface (there is no
/etc/sysconfig/network/ifcfg-
file
for this interface). Fortunately this rule has some exceptions, among
them all interface names starting with
tun
and all interface names starting
with tap
. Therefore we will name the
host interface tap0
in the following
section.
The following instructions explain how to create bridge on
openSUSE. Note that bridging on openSUSE hosts may not work properly
if you are using NetworkManager to manage your network connections. To
create a bridge on a recent openSUSE host, you must first install the
bridge utilities (bridge-utils
)
package. If you are working from the command line this can be done as
follows:
sudo /sbin/yast -i bridge-utils
Then you must create a text file describing the bridge to be
created. The name of the file must correspond to the name of the
bridge you wish to create. To create the bridge
br0
, you should call the file
/etc/sysconfig/network/ifcfg-br0
.
Below we have given an example of a file which creates a bridge
including the network device eth0
,
obtains an IP address by DHCP (through the network device) and is
started automatically when openSUSE starts. You will probably want to
adjust this to match your networking requirements.
BOOTPROTO='dhcp' NETMASK='255.255.255.0' STARTMODE='auto' USERCONTROL='no' DHCLIENT_TIMEOUT=30 BRIDGE='yes' BRIDGE_PORTS='eth0'
For this example to work, you will also need to change the
configuration for the network interface
eth0
to a static IP address of
0.0.0.0, as openSUSE does not do this automatically when the interface
is added to the bridge. You can do this using the graphical interface
or by changing the following settings in the file
/etc/sysconfig/network/ifcfg-eth-xx:xx:xx:xx:xx:xx
,
where the last part should be replaced with the hardware address of
the network card.
BOOTPROTO='static' IPADDR='0.0.0.0'
You can activate the bridge immediately after creating it with the command:
sudo /sbin/ifdown eth0 sudo /sbin/ifup br0
The bridge will be activated automatically from now on when the host is restarted.
Now, to create a permanent host interface called
tap0
(all host interfaces created in
this way must be called tap
followed
by a number) and add it to the network bridge created above, use the
following command (see Sectioná6.8.1.5, “Host Interface Networking utilities for Linux” for more
details):
sudo VBoxAddIF tap0 <user> br0
Replace <user>
with the
name of the user who is supposed to be able to use the new
interface.
To tell VirtualBox to use this interface
(tap0
) for a virtual machine, select
the VM in the main window, configure one of its network adaptors to
use Host Interface Networking (using "Settings", "Network", "Attached
to") and enter "tap0" into the "Interface name" field. You can only
use a given interface (tap0
,
tap1
and so on) with a single virtual
machine.
Alternatively, you can use the VBoxManage command line tool (in this example we are attaching the interface to the first network card of the virtual machine "My VM":
VBoxManage modifyvm "My VM" -hostifdev1 tap0
To create a bridge on Redhat and Fedora, you must first install
the bridge utilities (bridge-utils
)
package. Then you must create a configuration file describing the
bridge you wish to create. The following is the contents of an example
configuration file
/etc/sysconfig/network-scripts/ifcfg-br0
,
which sets the bridge br0 to get its IP address using DHCP and to
start automatically when the system is started. You will probably want
to adjust this to match your networking requirements.
DEVICE=br0 TYPE=Bridge BOOTPROTO=dhcp ONBOOT=yes
To add the network card eth0
to
the bridge, add the following line to the end of the file
/etc/sysconfig/network-scripts/ifcfg-eth0
:
BRIDGE=br0
You can activate the bridge immediately after creating it with the command:
sudo /sbin/service network restart
The bridge will be activated automatically from now on when the host is restarted.
Now, to create a permanent host interface called
vbox0
(all host interfaces created in
this way must be called vbox
followed
by a number) and add it to the network bridge created above, use the
following command (see Sectioná6.8.1.5, “Host Interface Networking utilities for Linux” for more
details):
sudo VBoxAddIF vbox0 <user> br0
Replace <user>
with the
name of the user who is supposed to be able to use the new
interface.
To tell VirtualBox to use this interface
(vbox0
) for a virtual machine, select
the VM in the main window, configure one of its network adaptors to
use Host Interface Networking (using "Settings", "Network", "Attached
to") and enter "vbox0" into the "Interface name" field. You can only
use a given interface (vbox0
,
vbox1
and so on) with a single
virtual machine.
Alternatively, you can use the VBoxManage command line tool (in this example we are attaching the interface to the first network card of the virtual machine "My VM":
VBoxManage modifyvm "My VM" -hostifdev1 vbox0
Most modern Linux distributions provide their own way of setting up ethernet bridges. We recommend that you follow the instructions provided by your distribution to do this. For distributions which do not provide their own method of creating bridges, we provide generic instructions below. Please ensure that you thoroughly understand how your distribution's networking scripts work before following these instructions, as they involve making changes to your host network configuration in ways normally only done by the networking scripts, and as such may interfere with your network setup.
First of all, you will need to install the bridge utilities
(usually named bridge-utils
or
similar). Once installed, as root
,
follow these instructions to create and configure a bridge:
Create a new bridge with this command:
brctl addbr br0
If you are not using DHCP, run
ifconfig
and note down the
network configuration of your existing network interface (e.g.
eth0
), which we will need to
copy to the bridge in a minute.
Remove the IP address configuration from the existing
network device (e.g. eth0
)
with:
ifconfig eth0 0.0.0.0
Warning: You will lose
network connectivity on eth0
at
this point.
Add your network adapter to the bridge:
brctl addif br0 eth0
Transfer the network configuration previously used with your physical ethernet adapter to the new bridge. If you are using DHCP, this should work:
dhclient br0
Otherwise, run ifconfig br0 x.x.x.x
netmask x.x.x.x
and use the values that you
noted down previously.
To create a permanent host interface called
vbox0
(all host interfaces
created in this way must be called
vbox
followed by a number) and
add it to the network bridge created above, use the following
command (see Sectioná6.8.1.5, “Host Interface Networking utilities for Linux” for more
details):
VBoxAddIF vbox0 <user> br0
Replace <user>
with
the name of the user who is supposed to be able to use the new
interface.
Although Linux comes with built-in support for virtual
networking interfaces, there are not many programs available for
managing these. VirtualBox supplies three tools for this purpose:
VBoxAddIF
,
VBoxDeleteIF
and
VBoxTunctl
. The last of these is in
fact the tunctl
utility from the User
Mode Linux project. In this section, we describe how to use these
utilities.
VBoxAddIF
creates a permanent
TAP interface which does not go away when the host system is
restarted. This interface should be called
vbox0
,
vbox1
or similar. The following
command creates the interface vbox0
for the user <user>
and adds it
to the bridge br0
. If you do not wish
to add the interface to a bridge, you can leave off the bridge
name.
sudo VBoxAddIF vbox0 <user> br0
Change the interface, user and bridge names to fit your own setup.
To remove an interface which you have created with
VBoxAddIF
, use the following command.
Replace vbox0
with the name of the
interface.
sudo VBoxDeleteIF vbox0
To create a temporary TAP interface which will disappear when
the host system is restarted, use the
VBoxTunctl
command. The following
example creates the interface vbox0
for the user <user>
:
sudo VBoxTunctl -t vbox0 -u <user>
If you have installed the bridge utilities (see the preceding sections), you can add this temporary interface to an Ethernet bridge using the command
sudo brctl addif br0 vbox0
Replace br0
with the name of
the bridge and vbox0
with the name of
the interface. Before you can use the interface, you will still need
to make it active (or "bring it up" in networking terminology, usually
using the standard Linux ifconfig
utility) and configure it with an IP address and related information.
To remove a temporary interface, do the following, replacing
vbox0
with the name of the interface
to be removed:
sudo VBoxTunctl -d vbox0
As an alternative to the permanent interfaces described
previously, you can tell VirtualBox to execute commands (usually
scripts) to set up your network dynamically, every time a virtual
machine starts or stops. This is normally done in order to create the
TAP interfaces at VM startup time, although you can also use this
feature to configure existing interfaces. If you are not using permanent
interfaces then the startup command should write the name of the
interface which it has created, typically something like
tap0
or
tap2
, to its standard output (the
VBoxTunctl -b
command does exactly
this) and the command executed when the machine stops should remove the
interface again.
The commands and scripts used will depend on the networking configuration that you want to set up. Both commands are given a file descriptor to the Linux TAP device as their first argument (this is only valid if the virtual machine is using previously created interfaces) and the name of the interface, if it is known, as the second argument. In most circumstances, you will only want to use the second argument.
Here is an example of a set up script which creates a TAP
interface and adds it to the network bridge
br0
.
#!/bin/bash # Create a new TAP interface for the user 'vbox' and remember its name. interface=`VBoxTunctl -b -u vbox` # If for some reason the interface could not be created, return 1 to # tell this to VirtualBox. if [ -z "$interface" ]; then exit 1 fi # Write the name of the interface to the standard output. echo $interface # Bring up the interface. /sbin/ifconfig $interface up # And add it to the bridge. /sbin/brctl addif br0 $interface
If this script is saved as
/home/vbox/setuptap.sh
and made
executable, it can be used to create a TAP interface when a virtual
machine is started, by configuring one of the machines network adapters
to use Host Interface Networking (without specifying a device in the
"Interface Name" field) and entering gksudo
/home/vbox/setuptap.sh
into the "Setup Application"
field (replace gksudo
by
kdesu
, or whatever is appropriate for
your system). Alternatively you can use the the VBoxManage command line
tool (in the following example for a machine called "Linux VM"):
VBoxManage modifyvm "Linux VM" -tapsetup1 "gksudo /home/vbox/setuptap.sh"
An example of a matching script to remove the interface from the bridge and shut it down would be:
#!/bin/bash # Remove the interface from the bridge. The second script parameter is # the interface name. /sbin/brctl delif br0 $2 # And use VBoxTunctl to remove the interface. VBoxTunctl -d $2
If this is saved as
/home/vbox/cleanuptap.sh
and made
executable, the virtual machine can be told to execute it when it shuts
down by entering gksudo
/home/vbox/cleanuptap.sh
, into the "Termination
Application" field in VirtualBox's network configuration settings, or by
using VBoxManage:
VBoxManage modifyvm "Linux VM" -tapterminate1 "gksudo /home/vbox/cleanuptap.sh"
The VBoxSDL
front end to
VirtualBox (see Sectioná7.3, “VBoxSDL, the simplified VM displayer”) allows for an additional
way of configuring TAP interfaces if it is started from a custom
parent process. This parent process can allocate the required TAP
interfaces and let VirtualBox inherit the file handles. For this to
work, the file descriptor has to be passed to
VBoxSDL
using the option
-tapfd<N> <fd>
. In this
case, the setup and termination scripts will not be called.
[12] A useful introduction to bridging can be found here: http://gentoo-wiki.com/HOWTO_setup_a_gentoo_bridge. While this is targeted at a Gentoo system, it contains a useful generic introduction.